/*
 *  Copyright 2003 by Texas Instruments Incorporated.
 *  All rights reserved. Property of Texas Instruments Incorporated.
 *  Restricted rights to use, duplicate or disclose this code are
 *  granted through contract.
 *  
 */
/* "@(#) DDK 1.10.00.23 07-02-03 (ddk-b12)" */

/*
 *  ======== c5509_usb.h ========
 *  This file defines the external interface of C5509_USB to user.
 */

#ifndef C5509_USB_
#define C5509_USB_

#include <std.h>
#include <csl.h>
#include <csl_std.h>
#include <csl_usb.h>
#include <iom.h>


#ifdef __cplusplus
extern "C" {
#endif

/*
 * BIOS driver version number defns.
 */
#define C5509_USB_VERSION_1  0xAB01  /* 0xAB01 is version 1,0xAB02 is 2, etc */

/* 
 *  This control code is used to connect the device 
 *    to the host before USB transactions can be performed.
 *  Applications typically use SIO_ctrl() or GIO_control() API with
 *   the 'cmd' param = C5509_USB_DEVICECONNECT. 
 */
#define C5509_USB_DEVICECONNECT  IOM_CNTL_USER

/* 
 *  This control code is used to retrieve USB state information from
 *   the USB device driver. The user passes the address of a 
 *   C5509_USB_StateInfo data structure to be filled in by the driver.
 *  Refer to USB 1.x Spec chapter 9.  
 */
#define C5509_USB_GETSTATEINFO   IOM_CNTL_USER + 1

/*
 * C5509_USB_DevParams defaults.
 */
#define C5509_USB_IER0MASKDEFAULT   1   /* ier0mask = 1 to mask self(USB) */
#define C5509_USB_IER1MASKDEFAULT   1   /* ier1mask = 1.  "               */
#define C5509_USB_INCLK12MHZ        12  /* USB inclk, input clock is 12 Mhz */
#define C5509_USB_PLLDIVDEFAULT     0   /* plldiv, PLL divide value = 0 */
#define C5509_USB_PSOFTMRCNTDEFAULT 128 /* pSofTmrCnt, PSOF value */ 


/*
 *  C5509_USB_EndptDesc:
 *
 *  This is the USB endpoint descriptor used by the USB CSL.
 *
 *  reserved is used by transfer API, not an integral desc part.
 *
 *  ltmask is the length & desc type mask.
 *
 *  addrsmask is the ep address and transfer attributes.
 *
 *  maxPktLen is the max transfer pkt size in bytes.
 *
 *  interval;  host uses for scheduling USB requests (8 lsb bits used)
 */
typedef struct C5509_USB_EndptDesc {
    Uint16 reserved;  /* Used by transfer API, not an integral desc part */
    Uint16 ltmask;    /* length & desc type mask */
    Uint16 addrsmask; /* ep address and transfer attributes */
    Uint16 maxPktLen; /* max transfer pkt size in bytes */
    Uint16 interval;  /* one lsb used; host uses for scheduling */
} C5509_USB_EndptDesc;

/*
 *  This is the application-level callback function for
 *   USB bus connection notification.. 
 */
typedef Void (*C5509_USB_TappCallback)(Ptr arg);

/*
 *  The application code can pass a pointer to this structure
 *   for the function 'fxn' to be called with arguments as defined
 *   by the C5509_USB_TappCallback typedef above. This structure is used
 *   by the C5509_USB_DEVICECONNECT control command code to allow application
 *   code to register a callback function to be invoked when the USB bus
 *   is connected.
 */
typedef struct C5509_USB_AppCallback {
    C5509_USB_TappCallback      fxn;
    Ptr                 arg;
} C5509_USB_AppCallback;


/*  
 *  IOM channel object. 
 *  The channel object is used internally to the IOM driver,
 *   but users declare channel object memory to alleviate the need
 *   for dynamic memory allocation in the driver.
 *  One IOM channel object is associated with one CSL USB endpoint.
 */  
typedef struct C5509_USB_ChanObj {
    Uns mode;                           /* data flow direction */
    USB_EpObj epObj;                    /* USB CSL endpoint object */ 
    IOM_Packet *flushPacket;           /* IOM_FLUSH/ABORT packet */
    IOM_Packet *dataPacket;            /* current active I/O packet */
    QUE_Obj pendList;                   /* list of packets for I/O */
    IOM_TiomCallback cbFxn;             /* IOM callback */
    Ptr  cbArg;                         /* IOM callback argument */
    C5509_USB_TappCallback fxnConnect;  /* Fxn called when bus is connected */
    Ptr argConnect;                     /* argument to fxnConnect() */
} C5509_USB_ChanObj, *C5509_USB_ChanHandle;


/*
 *  C5509_USB_EpConfig:
 *   
 *  This is the endpoint configuration array used in devParams to configure
 *    a USB interface.
 *   
 *  chanp is the pointer to an IOM channel object.
 *
 *  epNum is the number (e.g. USB_OUT_EP2). 
 *
 *  epType is the EndPt transfer type (e.g. USB_BULK).
 *
 *  epEvtMask is the USB endpoint events mask.(e.g. USB_EVENT_EOT).
 */
typedef struct C5509_USB_EpConfig {
    C5509_USB_ChanHandle chanp; /* IOM channel handle */
    USB_EpNum    epNum;         /* Endpoint number (e.g. USB_OUT_EP2) */
    USB_XferType epType;        /* Endpoint transfer type (e.g. USB_BULK) */
    Uint16       epMaxPktLen;   /* Maximum USB packet size(bytes) allowed */
    Uint16       epEvtMask;     /* USB endpoint event msk(e.g USB_EVENT_EOT) */
} C5509_USB_EpConfig;


/*
 *  C5509_USB_IfcConfig:
 *  
 *  The USB interface configuration of endpoints.
 *
 *  numEps is the total number of configured endpoints
 *
 *  usbConfig is a pointer to the USB config and alt i/f(s).
 *
 *  epConfig is the array of endpoint configurations.
 *
 */
typedef struct C5509_USB_IfcConfig {
    Uint16                 numEps;     /* total number of endpoints */
    USB_DataStruct        *usbConfig;  /* USB config and alt i/f(s) */    
    C5509_USB_EpConfig    *epConfig;   /* USB driver endpoint configuration */ 
} C5509_USB_IfcConfig;


/*
 *  ======== usb default event handler type ========
 *  This is the function pointer type is used to override the mini-driver's 
 *  event handler. If non-NULL this event handler is for usb non-setup events. 
 *  When host requests RESET or SUSPEND for example, this event handler gets
 *  called by the mini-driver for the application to process.
 */
typedef Void (*C5509_USB_UsbEventHandler)() ;
                          
/* 
 *  ======== USB control events callbacks ========
 *  When the event occurs, the mini-driver passes the default handler
 *  and calls back to the application.
 */

/*  
 *  Event(non-setup) callback
 */
typedef Void (*C5509_USB_EventCb) (  
        Uint16 event,    /* event */ 
        C5509_USB_UsbEventHandler handler); 

/*
 *  return values for USB request handlers
 */
typedef enum {
    C5509_USB_REQUEST_DONE = 0,  /* Request done. Can call again after setup */
    C5509_USB_REQUEST_STALL,     /* STALL the control endpoint */
    C5509_USB_REQUEST_SEND_ACK,  /* Send a 0 length IN packet */
    C5509_USB_REQUEST_GET_ACK,   /* Prepare to receive 0 length OUT packet */
    C5509_USB_REQUEST_DATA_IN,   /* Notify handler when IN data transmitted */
    C5509_USB_REQUEST_DATA_OUT   /* Notify handler when OUT data received */
} C5509_USB_UsbReqRet;

/*
 *  usb request handler type 
 */                                
typedef C5509_USB_UsbReqRet(*C5509_USB_UsbReqHandler)();


/*
 *  Setup event callback 
 */
typedef C5509_USB_UsbReqRet(*C5509_USB_SetupEventCb) (
        Uint16 requestId,
        C5509_USB_UsbReqHandler handler,
            USB_SetupStruct *setupPacket );


/*
 *  C5509_USB_DeviceConfig:
 *
 *  Device configuration info.
 *
 *  deviceDesc is the device descriptor.
 *
 *  stringDesc is the string descriptor.
 *
 *  stringDescLangId is the language identifier.
 *
 *  eventHandler is the non-setup event handler. If NULL, then use default.
 *
 *  setupEventHandler is the setup event handler for usb setup events. Set
 *    to NULL to use default handler.
 *
 */
typedef struct C5509_USB_DeviceConfig {
    Uint16  *deviceDesc;          /* device descriptor */   
    Uint16  *stringDescLangId;    /* string desc language id */  
    String  *stringDesc;          /* string descriptor */
    C5509_USB_EventCb eventHandler;           /* non-setup event handler */ 
    C5509_USB_SetupEventCb setupEventHandler; /* setup event handler */ 
} C5509_USB_DeviceConfig;


/*
 *  C5509_USB_DevParams struct:
 *   
 *  This is the device parameter struct which should be statically filled
 *  by user and passed to mdBindDev.
 *   
 *  versionId is the mini-driver revision number. If the revision is not 
 *   supported by the driver the mdBindDev mini-driver fxn will return error.
 *
 *  ier0mask is the IER0 mask used by HWI_dispatchPlug in mdBindDev.
 *
 *  ier1mask     "  IER1      "                    "
 *
 *  inclk is the input clock freq(Mhz at CLKIN pin) used to init the USB CSL.
 *   deviceConfig is the USB device, string & lang id descriptors ptrs.
 *
 *  plldiv is the input clock divide down value (CLKIN pin). 
 *
 *  pSofTmrCnt is the 8-bit counter value for the Pre USB Start-of-Frame timer.
 *  ifcConfig is the usb endpoint configuration pointer.
 *
 *  deviceConfig is the USB device, language, and string descriptor.
 * 
 *  ifcConfig is the USB interface descriptor(s).
 * 
 */
typedef struct C5509_USB_DevParams {    /* C5509_USB_DevParams */
    Int versionId;  /* version of mini-driver(e.g C5509_USB_VERSION0)  */
    Uns ier0mask;   /* IERx masks used by HWI_dispatchPlug in mdBindDev, */
    Uns ier1mask;   /* set ier0mask=1 & ier1mask=1 to mask USB intr only */
    Uns inclk;      /* input clock freq(Mhz at CLKIN pin). See USB_initPLL */
    Uns plldiv;     /* input clock divide down value (CLKIN pin). */
    SmUns pSofTmrCnt; /* 8-bit counter value for pre-SOF timer. See USB_init */
    C5509_USB_DeviceConfig  *deviceConfig;  /* device, string & lang id desc */
    C5509_USB_IfcConfig  *ifcConfig; /* usb endpoint interface configuration */
} C5509_USB_DevParams;

/*
 *  C5509_USB_StateInfo struct.
 *  This structure contains internal USB state information returned
 *    to the application by using the C5509_USB_GETSTATEINFO cmd code.
 *  See USB spec. 1.x chapter 9 standard request implementation. 
 */
typedef struct C5509_USB_StateInfo {
    Uint16 usbCurConfig;      /* current USB configuration number */
    Uint16 usbCurIntrfc;      /* current USB interface number */ 
    Uint16 usbCurAltSet;      /* current USB alternate set number */
    Uint16 usbCurDev;         /* current USB device state. 1 = self powered */ 
} C5509_USB_StateInfo;

/*
 * The following are USB descriptor definitions types. Refer to USB 1.x spec.
 */
#define C5509_USB_DESCRIPTOR_DEVICE               0x01   
#define C5509_USB_DESCRIPTOR_CONFIG               0x02
#define C5509_USB_DESCRIPTOR_STRING               0x03
#define C5509_USB_DESCRIPTOR_INTRFC               0x04
#define C5509_USB_DESCRIPTOR_ENDPT                0x05
#define C5509_USB_DESCRIPTOR_POWER                0x06
#define C5509_USB_DESCRIPTOR_HID                  0x21

#ifdef __cplusplus
}
#endif

#endif        /* C5509_USB_ */



